.if \n[NESTED] \{\
.so ../bk-macros
.TH "bk portal" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk portal \- set or show the portal status of a nested collection
.SH SYNOPSIS
.B bk portal
.[B] \-q
.B .
.br
.B bk portal
.[B] \-q
.B \-r
.SH DESCRIPTION
.LP
The
.B bk portal
command either reports whether the nested collection is a portal
or it changes that nested collection to a portal.
.LP
A 
.I portal
nested collection is part of \*[BK]'s product line functionality.
There should be one, and only one, portal for any nested collection.
.LP
With an argument of ".", this command marks the nested collection as a portal.
With no argument, the command prints the portal status.
With 
.BR \-q ,
the exit status indicates portal status; 0 means it is, 1 means it is not.
.LP
A component in a portal may be the destination of a 
.B "bk port"
command; non-portals may not be such a destination.
External repositories may be attached to a portal; non-portal attaches
are not allowed.
It is suggested that creating and modifying aliases is done in the portal.
.LP
For any given set of clones of a nested collection, only one instance
should be a portal.
If multiple instances are marked as portals the following are examples
of problems that can, and likely will, occur:
.TP
\*(BU
The same external repository could be attached multiple times.  To get
rid of the name conflict when these collide means that the product will
need to be run through bk csetprune which means the resulting instance
will no longer interact with older instances.
.TP
\*(BU
The same changesets can be ported into the history at different points
in time, creating what is called the "poly problem", where the same
component changeset[s] belong to multiple product changesets.  
.SH RESTRICTIONS
Inside of a portal, commands that would remove information are disallowed.
bk undo, bk collapse, bk unpopulate are examples of such commands.
It is common that many other clones depend on the portal to be a 
"safe" container of changes so removing information is not allowed 
by default.
.LP
If it happens that a changeset gets pushed to a portal that really must
be removed, then remove the portal status, undo (or unpull) the changeset,
and put the portal status back.
.SH OPTIONS
.TP
.B \-r
Unmark the current product as a portal.
.tp
.B \-q
Run silently.
.SH "SEE ALSO"
.SA attach
.SA gate
.SA port
.SH CATEGORY
.B Nested
.\}
